---
title: DisplayModes
slug: /displaymodes
section: Screen & Viewport
---

Excalibur can render the screen in various different display modes by default.

```twoslash include ex
/// <reference path="../src/engine/excalibur.d.ts" />
```

## Managing display modes

Excalibur supports multiple display modes for a game. Pass in a [[EngineOptions.displayMode|displayMode]]
option when creating a game to customize the viewport.

### Fixed Display Mode

[[DisplayMode.Fixed]] is the default, use a specified resolution for the game. Like 600x400 pixels for example.

```ts twoslash {4}
// @include: ex
// ---cut---
const game = new ex.Engine({
    width: 600,
    height: 400,
    displayMode: ex.DisplayMode.Fixed // fixed is the default so this is optional
});
```

<div class="snippet-resizer snippet-border" alt="Resize me!">

<IFrameEmbed className="snippet-resized" src="https://excaliburjs.com/excalibur-snippets/displaymode/fixed/" />

</div>

### Fit Screen Display Mode

[[DisplayMode.FitScreen]] Fit to screen using as much space as possible while maintaining aspect ratio and resolution.

This is not the same as [[Screen.enterFullscreen]], which uses the fullscreen api, but behaves in a similar way maintaining aspect ratio.

You may want to center your game and fit to the screen here is an example:

```css
html, body {
    height: 100%;
}
body {
    display: flex;
    height: 100vh;
    justify-content: center;
    align-items: center;
}
```

```ts twoslash {4}
// @include: ex
// ---cut---
const game = new ex.Engine({
    width: 600,
    height: 400,
    displayMode: ex.DisplayMode.FitScreen
});
```

<div class="snippet-resizer snippet-border" alt="Resize me!">

<IFrameEmbed className="snippet-resized" src="https://excaliburjs.com/excalibur-snippets/displaymode/fitscreen/" />

</div>

Click and drag right corner to resize!

### Fill Screen Display Mode

[[DisplayMode.FillScreen]] Fill the entire screen's css width/height for the game resolution dynamically. This means the resolution of the game will change dynamically as the window is resized. This is not the same as [[Screen.enterFullscreen]]

```ts twoslash {1}
// @include: ex
// ---cut---
const game = new ex.Engine({
    displayMode: ex.DisplayMode.FillScreen
});
```

<div class="snippet-resizer snippet-border" alt="Resize me!">

<IFrameEmbed className="snippet-resized" src="https://excaliburjs.com/excalibur-snippets/displaymode/fillscreen/" />

</div>

Click and drag right corner to resize!

### Fit Container Display Mode

[[DisplayMode.FitContainer]] Fit to parent element width/height using as much space as possible while maintaining aspect ratio and resolution.

```css
.container {
    /* Flexbox used to center game */
    display: flex;
    justify-content: center;
    align-items: center;

    /* Container size with border */
    border: red 4px dashed;
    width: 50%;
    height: 300px;
}

.snippet-resizer { display:flex; margin:0; padding:0; resize:both; overflow:hidden }
.snippet-resizer > .snippet-resized { flex-grow:1; margin:0; padding:0; border:0 }
```

```html
<div class="container snippet-resizer">
    <canvas id="game"></canvas>
</div>
```

```ts twoslash {5}
// @include: ex
// ---cut---
const game = new ex.Engine({
    canvasElementId: 'game',
    width: 600,
    height: 400,
    displayMode: ex.DisplayMode.FitContainer
});
```

<div class="snippet-resizer snippet-border" alt="Resize me!">

<IFrameEmbed className="snippet-resized" src="https://excaliburjs.com/excalibur-snippets/displaymode/fitcontainer/" />

</div>

Click and drag right corner to resize!

### Fill Container Display Mode

[[DisplayMode.FillContainer]] will fill the entire screen's css width/height for the game resolution dynamically. This means the resolution of the game will change dynamically as the window is resized. This is not the same as [[Screen.enterFullscreen]]

```css
.container {
    border: red 4px dashed;
    width: 50%;
    height: 300px;
}

.snippet-resizer { display:flex; margin:0; padding:0; resize:both; overflow:hidden }
.snippet-resizer > .snippet-resized { flex-grow:1; margin:0; padding:0; border:0 }
```

```html
<div class="container snippet-resizer">
    <canvas id="game"></canvas>
</div>
```

```ts twoslash {3}
// @include: ex
// ---cut---
const game = new ex.Engine({
    canvasElementId: 'game',
    displayMode: ex.DisplayMode.FillContainer
});
```

<div class="snippet-resizer snippet-border" alt="Resize me!">

<IFrameEmbed className="snippet-resized" src="https://excaliburjs.com/excalibur-snippets/displaymode/fillcontainer/" />

</div>

Click and drag right corner to resize!

### Fit Screen And Fill Display Mode

[[DisplayMode.FitScreenAndFill]] is similar to [[DisplayMode.FitScreen]] and will fit the game in the screen while preserving the original aspect ratio, but allow the excess gaps to be drawn to. This ensures there is no "letterboxing" and the entire screen is covered by canvas. You can use the [[Screen.contentArea]] to return a screen space bounding box of area of the screen guaranteed to be visible to the user.

![Content area](content-area.png)

<div class="snippet-resizer snippet-border" alt="Resize me!">

<IFrameEmbed className="snippet-resized" src="https://excaliburjs.com/excalibur-snippets/displaymode/fitscreenandfill/" />

</div>

Click and drag right corner to resize!

### Fit Container And Fill Display Mode

[[DisplayMode.FitContainerAndFill]] is similar to [[DisplayMode.FitContainer]] and will fit the game to the the current container preserving the original aspect ratio, but allow the excess gaps in the container to be drawn to. You can use the [[Screen.contentArea]] to return a screen space bounding box of area of the screen guaranteed to be visible to the user.

![Content area](content-area.png)

<div class="snippet-resizer snippet-border" alt="Resize me!">

<IFrameEmbed className="snippet-resized" src="https://excaliburjs.com/excalibur-snippets/displaymode/fitcontainerandfill/" />

</div>

Click and drag right corner to resize!

## Fullscreen API
:::warning

Currently Apple does not support fullscreen API on iPhones, it does however work on later model iPads.

:::

The screen abstraction now supports the [browser fullscreen api](https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API). This will cause the game to be displayed fullscreen until the user exits (usually with the escape key or by gesturing to the exit button at the top of the browser window).

<div class="snippet-resizer snippet-border" alt="Resize me!">

<IFrameEmbed className="snippet-resized" src="https://excaliburjs.com/excalibur-snippets/fullscreen/" />

</div>

Click and drag right corner to resize!

:::note

This requires an explicit user gesture due to browser security, so wiring it into a native HTML button click is the easiest way to do this.

:::

```typescript
document.getElementById('go-fullscreen')!.addEventListener('click', () => {
    game.screen.enterFullscreen();
});
```


```typescript
await game.screen.enterFullscreen();

await game.screen.exitFullscreen();
```

By default `enterFullscreen()` will use the canvas element as the root of full screen mode. If your game uses [HTML based UI](/docs/ui#html-based-ui), the HTML UI will not be included because it is not a child of the canvas element.

To include both the HTML based game UI as well as the game canvas, pass an id of an element that is the parent of both the canvas and UI. For example `enterFullscreen('root')`
